Skip to content

Device apps (portal): contract 1 — every app from the API, labelled choices, the owner's port, opened by protocol - #1340

Merged
evanrbowers merged 3 commits into
apps-contract-1from
ac1/portal-contract-1
Nov 17, 2026
Merged

evanrbowers merged 3 commits into
apps-contract-1from
ac1/portal-contract-1

Conversation

@evanrbowers

Copy link
Copy Markdown
Contributor

The portal side of remote.it apps contract 1 (remoteit/apps docs/contract.md; presence-server #77 docs/self-contained-apps.md, "What the implementation changes — the portal"), on the apps-contract-1 integration branch. It supersedes #1336, whose commit (f8be8bdb: every app drawn from what the API says, no console UI, no console detection) is the first of the two here, reworked onto contract 1 by the second.

What changes against #1336

  • Labelled choices. A choice is {value, label}. The portal shows the label and sets the value. A choice given as a string (the manifest's shorthand), or one without a label, is labelled by its value (deviceAppsShared.choiceOf), for device and product settings alike. Forced choices are matched by value, as before.
  • The owner's port. DeviceApp.portSetting names the setting that is the service's port (service.port: "${setting.X}"). That setting is edited under Service ("Port people connect to"), not again under Settings. While the app is disabled its service is stopped, so the setting stays under Settings.
  • Opened by protocol.
    • http/https opens a page ("Open page").
    • vnc/rdp opens a viewer ("Open screen", with its own icon).
    • ssh with person-certificates opens a terminal.
    • The connection is the service's, whose type graphql makes from the protocol.
    • The terminal checks the key's fingerprint against sshHostKey, as before.
  • Sessions are what the app writes in status.json, {session, login, via, since}. Each is shown by its session id and never names a person: an app knows sessions, not who is behind them.
  • New fields read: DeviceApp.contract, features and portSetting. AvailableApp now carries protocol, capabilities and contract itself, so Add an app no longer reads the account's catalogue just to describe what it offers.
  • CatalogApp drops kind and serves. Contract 1 has run and listen, which are the daemon's to read. "Stopped while the app is disabled" is now said wherever the release names a protocol.
  • The temporary console fallback (consoleUntilDeclared.ts) is gone. graphql names no app and serves the console at its app host (remoteit-app-remoteit-console). A service at remoteit-console is now nobody's app.

Depends on graphql (apps-contract-1)

The fields named in the shared interfaces:

  • DeviceApp: contract, protocol, capabilities, hostKey, sessions { session login via since }, sessionsOpen, features, portSetting;
  • DeviceAppSettingChoice.label (non-null);
  • AvailableApp, CatalogApp and CatalogAppRelease: protocol, capabilities, contract.

An older graphql refuses these queries, so graphql ships first.

Gates

  • tsc --noEmit is clean.
  • vitest run: 216 files and 2140 tests pass.
  • vite build passes.
  • npm run i18n:extract -w=frontend was run and the catalogs are committed (new keys in en; de/es/ja empty, as the repo keeps untranslated keys). i18n:check passes.

New tests:

  • labelled and shorthand choices;
  • the fields asked, and sessions without a person;
  • the port setting under Service, and under Settings while the app is disabled;
  • Open in the protocol's words;
  • AvailableApp's capabilities in the catalogue and the consent;
  • remoteit-console no app's host;
  • the catalogue query without kind/serves.

🤖 Generated with Claude Code

Evan Bowers and others added 2 commits November 15, 2026 07:11
…sole UI, no console detection

The portal had a part of its own for one app: FIRST_PARTY_APPS = {console} (ConsoleApp: its icon, state words,
ai_commands label, host key, Open terminal) and a console service found by type 28 at host remoteit-console
(sshHelper isConsoleService, in the services' rows, the connect panel and the device's name on this machine). An app
anyone ships could have none of it (presence-contract docs/self-contained-apps.md, the portal's row and
"Capabilities, as the platform keeps them"). Now every app is drawn from DeviceApp, CatalogApp and
CatalogAppRelease alone:

- protocol, capabilities, hostKey, sessions and sessionsOpen are read with an app; protocol and capabilities with
  a catalogue entry and each release (and a product's app, where the schema has them).
- An app whose service is ssh and that declares person-certificates (sshHelper opensTerminal) opens in web SSH,
  with the person's own account, a certificate and its host key checked: Open terminal in the Apps section and on
  its page, the terminal button in its device's services and the option in its connect panel (AppTerminal, which
  replaces ConsoleTerminal), the plain ssh command and its hint by name. Its service is the one its app names
  (DeviceApp.serviceId), or — disabled, naming none — the one at its app host (remoteit-app-<publisher>-<app>);
  a device's apps are read only for a service at an app host.
- The app's page says its state in the shared words, its settings in its release's labels and help (ai_commands
  included), the key its service presents where the device reports one, and the sessions it serves: how many, and
  who, as whom, by an AI and since when for those who manage it. Its icon comes from its protocol.
- What an app asks of remote.it beyond running is said in words beside Runs as root wherever it is offered — the
  catalogue, the device's catalogue (from its catalogue entry), the app and its releases, a product's apps — and is
  part of every root consent (the device's, the product's, Add's): "Keeps accounts for the people you share with",
  "Signs in people by remote.it certificate", "AI commands go through this app".
- This device's Advanced titles an app's on/off and its settings by the API's name and labels (the device by its
  UID), puts any app's settings under its row, and says "Not served" for an app that serves a service; only the
  device's own settings keep words here.

Until the console declares these (step 3) and its services move to its app host (step 4),
services/consoleUntilDeclared takes the console with no capabilities as declaring ssh, person-accounts,
person-certificates and ssh-exec, and its host remoteit-console as its app host, so it works as before. It is the
only place the portal names the console, and the removal step deletes it with its two calls. SCREENVIEW stays for
ScreenView's old install alone.

Needs graphql's DeviceApp.protocol/capabilities/hostKey/sessions/sessionsOpen and CatalogApp(Release)
.capabilities/protocol: an older graphql refuses these queries.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…, opened by protocol, sessions by id

The portal reads what graphql says of an app under remoteit/apps contract 1, and names no app:

- Choices are {value, label}: the label shown, the value set; the manifest's string shorthand (or a choice without
  a label) is labelled by its value (deviceAppsShared choiceOf), for device and product settings alike.
- DeviceApp.portSetting: the setting that is the service's port is edited under Service ("Port people connect to")
  and not again under Settings; while the app is disabled, its service stopped, it stays under Settings.
- Opened by protocol: a page for http/https ("Open page"), a viewer for vnc/rdp ("Open screen", their icon), a
  terminal for ssh with person-certificates; the connection is the service's, whose type graphql makes from it.
- Sessions are the app's status.json: {session, login, via, since}, shown by the session id, never a person.
- DeviceApp.contract and .features are read; AvailableApp carries protocol/capabilities/contract itself, so the
  device's catalogue no longer reads the account's catalogue to describe its offers.
- CatalogApp drops kind and serves (contract 1 has run and listen, the daemon's to read); "stopped while
  disabled" is said where the release names a protocol.
- The temporary console fallback (consoleUntilDeclared) is gone: graphql names no app and serves the console at
  its app host.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@evanrbowers

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T01:09:08.692952Z 8d51f9d Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa3971359c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

words
)}
</Typography>
<AppCapabilities capabilities={app?.capabilities} />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Show the target release's capabilities when requesting consent

When a user pins a different root release on the device app page, the consent dialog displays the currently installed app's capabilities rather than those of the release being approved. DeviceAppPage passes its existing app to RootConsent while keeping the target version separately in pinning, so capabilities added by the selected release (such as person-accounts or ssh-exec) are omitted from the confirmation. Resolve and pass the target release's capabilities from catalog.releases before presenting its consent.

Useful? React with 👍 / 👎.

…ing version's

A consent covers the release it moves the device (or product) to — a pin, Update now's waiting release, the release
enabling gives — and that release may ask more of remote.it than the version running. Every RootConsent now names the
capabilities of that release (`release`), read from its catalogue entry (useReleaseAsks), and its yes waits until they
are read; where no release is named, or the catalogue cannot say, the app's own are named (graphql still refuses a yes
that does not cover what the release asks). useAppSwitch passes the release it consents to and the device's account;
the pin's consent and a product's consent pass theirs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@evanrbowers

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 8d51f9d8ec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant